<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.5"/>
<title>Theron: Theron::Framework::Parameters Struct Reference</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/search.js"></script>
<script type="text/javascript">
  $(document).ready(function() { searchBox.OnSelectItem(0); });
</script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td style="padding-left: 0.5em;">
   <div id="projectname">Theron
   &#160;<span id="projectnumber">6.00.02</span>
   </div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.5 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search",false,'Search');
</script>
  <div id="navrow1" class="tabs">
    <ul class="tablist">
      <li><a href="index.html"><span>Main&#160;Page</span></a></li>
      <li><a href="namespaces.html"><span>Namespaces</span></a></li>
      <li class="current"><a href="annotated.html"><span>Classes</span></a></li>
      <li><a href="files.html"><span>Files</span></a></li>
      <li>
        <div id="MSearchBox" class="MSearchBoxInactive">
        <span class="left">
          <img id="MSearchSelect" src="search/mag_sel.png"
               onmouseover="return searchBox.OnSearchSelectShow()"
               onmouseout="return searchBox.OnSearchSelectHide()"
               alt=""/>
          <input type="text" id="MSearchField" value="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)" 
               onblur="searchBox.OnSearchFieldFocus(false)" 
               onkeyup="searchBox.OnSearchFieldChange(event)"/>
          </span><span class="right">
            <a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a>
          </span>
        </div>
      </li>
    </ul>
  </div>
  <div id="navrow2" class="tabs2">
    <ul class="tablist">
      <li><a href="annotated.html"><span>Class&#160;List</span></a></li>
      <li><a href="hierarchy.html"><span>Class&#160;Hierarchy</span></a></li>
      <li><a href="functions.html"><span>Class&#160;Members</span></a></li>
    </ul>
  </div>
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
<a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(0)"><span class="SelectionMark">&#160;</span>All</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(1)"><span class="SelectionMark">&#160;</span>Classes</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(2)"><span class="SelectionMark">&#160;</span>Namespaces</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(3)"><span class="SelectionMark">&#160;</span>Files</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(4)"><span class="SelectionMark">&#160;</span>Functions</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(5)"><span class="SelectionMark">&#160;</span>Variables</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(6)"><span class="SelectionMark">&#160;</span>Typedefs</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(7)"><span class="SelectionMark">&#160;</span>Enumerations</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(8)"><span class="SelectionMark">&#160;</span>Enumerator</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(9)"><span class="SelectionMark">&#160;</span>Macros</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(10)"><span class="SelectionMark">&#160;</span>Pages</a></div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

<div id="nav-path" class="navpath">
  <ul>
<li class="navelem"><a class="el" href="namespaceTheron.html">Theron</a></li><li class="navelem"><a class="el" href="classTheron_1_1Framework.html">Framework</a></li><li class="navelem"><a class="el" href="structTheron_1_1Framework_1_1Parameters.html">Parameters</a></li>  </ul>
</div>
</div><!-- top -->
<div class="header">
  <div class="summary">
<a href="#pub-methods">Public Member Functions</a> &#124;
<a href="#pub-attribs">Public Attributes</a> &#124;
<a href="structTheron_1_1Framework_1_1Parameters-members.html">List of all members</a>  </div>
  <div class="headertitle">
<div class="title">Theron::Framework::Parameters Struct Reference</div>  </div>
</div><!--header-->
<div class="contents">

<p><a class="el" href="structTheron_1_1Framework_1_1Parameters.html" title="Parameters structure that can be passed to the Framework constructor. ">Parameters</a> structure that can be passed to the <a class="el" href="classTheron_1_1Framework.html" title="Manager class that hosts, manages, and executes actors. ">Framework</a> constructor.  
 <a href="structTheron_1_1Framework_1_1Parameters.html#details">More...</a></p>

<p><code>#include &lt;Framework.h&gt;</code></p>
<table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="pub-methods"></a>
Public Member Functions</h2></td></tr>
<tr class="memitem:a8439362f7f85c0b66da0229a3104cadc"><td class="memItemLeft" align="right" valign="top">&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="structTheron_1_1Framework_1_1Parameters_a8439362f7f85c0b66da0229a3104cadc.html#a8439362f7f85c0b66da0229a3104cadc">Parameters</a> (const <a class="el" href="namespaceTheron_a254da7d1d07833b997828500fbf73daa.html#a254da7d1d07833b997828500fbf73daa">uint32_t</a> threadCount=16, const <a class="el" href="namespaceTheron_a254da7d1d07833b997828500fbf73daa.html#a254da7d1d07833b997828500fbf73daa">uint32_t</a> nodeMask=0x1, const uint32_t processorMask=0xFFFFFFFF, const YieldStrategy yieldStrategy=YIELD_STRATEGY_CONDITION, const float priority=0.0f)</td></tr>
<tr class="memdesc:a8439362f7f85c0b66da0229a3104cadc"><td class="mdescLeft">&#160;</td><td class="mdescRight">Constructor.  <a href="#a8439362f7f85c0b66da0229a3104cadc">More...</a><br/></td></tr>
<tr class="separator:a8439362f7f85c0b66da0229a3104cadc"><td class="memSeparator" colspan="2">&#160;</td></tr>
</table><table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="pub-attribs"></a>
Public Attributes</h2></td></tr>
<tr class="memitem:a403383f5c097f959a923e13ee9c2b694"><td class="memItemLeft" align="right" valign="top"><a class="el" href="namespaceTheron_a254da7d1d07833b997828500fbf73daa.html#a254da7d1d07833b997828500fbf73daa">uint32_t</a>&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="structTheron_1_1Framework_1_1Parameters_a403383f5c097f959a923e13ee9c2b694.html#a403383f5c097f959a923e13ee9c2b694">mThreadCount</a></td></tr>
<tr class="memdesc:a403383f5c097f959a923e13ee9c2b694"><td class="mdescLeft">&#160;</td><td class="mdescRight">The initial number of worker threads to create within the framework.  <a href="#a403383f5c097f959a923e13ee9c2b694">More...</a><br/></td></tr>
<tr class="separator:a403383f5c097f959a923e13ee9c2b694"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:a22b5df6a6870c48ee49ee8d504a70995"><td class="memItemLeft" align="right" valign="top"><a class="el" href="namespaceTheron_a254da7d1d07833b997828500fbf73daa.html#a254da7d1d07833b997828500fbf73daa">uint32_t</a>&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="structTheron_1_1Framework_1_1Parameters_a22b5df6a6870c48ee49ee8d504a70995.html#a22b5df6a6870c48ee49ee8d504a70995">mNodeMask</a></td></tr>
<tr class="memdesc:a22b5df6a6870c48ee49ee8d504a70995"><td class="mdescLeft">&#160;</td><td class="mdescRight">32-bit mask specifying the NUMA processor nodes upon which the framework may execute.  <a href="#a22b5df6a6870c48ee49ee8d504a70995">More...</a><br/></td></tr>
<tr class="separator:a22b5df6a6870c48ee49ee8d504a70995"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:a42e97de63f2f50b40ac6071b524e972e"><td class="memItemLeft" align="right" valign="top"><a class="el" href="namespaceTheron_a254da7d1d07833b997828500fbf73daa.html#a254da7d1d07833b997828500fbf73daa">uint32_t</a>&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="structTheron_1_1Framework_1_1Parameters_a42e97de63f2f50b40ac6071b524e972e.html#a42e97de63f2f50b40ac6071b524e972e">mProcessorMask</a></td></tr>
<tr class="memdesc:a42e97de63f2f50b40ac6071b524e972e"><td class="mdescLeft">&#160;</td><td class="mdescRight">32-bit mask specifying the subset of the processors in each NUMA processor node upon which the framework may execute.  <a href="#a42e97de63f2f50b40ac6071b524e972e">More...</a><br/></td></tr>
<tr class="separator:a42e97de63f2f50b40ac6071b524e972e"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:a7f0d63173a26929b741bd28e0caec82c"><td class="memItemLeft" align="right" valign="top"><a class="el" href="namespaceTheron_a03ee5f87e8369a84dc8f6f922677429c.html#a03ee5f87e8369a84dc8f6f922677429c">YieldStrategy</a>&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="structTheron_1_1Framework_1_1Parameters_a7f0d63173a26929b741bd28e0caec82c.html#a7f0d63173a26929b741bd28e0caec82c">mYieldStrategy</a></td></tr>
<tr class="memdesc:a7f0d63173a26929b741bd28e0caec82c"><td class="mdescLeft">&#160;</td><td class="mdescRight">Member of <a class="el" href="namespaceTheron_a03ee5f87e8369a84dc8f6f922677429c.html#a03ee5f87e8369a84dc8f6f922677429c">YieldStrategy</a> specifying how worker threads yield to other system threads when no work is available.  <a href="#a7f0d63173a26929b741bd28e0caec82c">More...</a><br/></td></tr>
<tr class="separator:a7f0d63173a26929b741bd28e0caec82c"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:a884e2844a969e177cf557322e3e047ea"><td class="memItemLeft" align="right" valign="top">float&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="structTheron_1_1Framework_1_1Parameters_a884e2844a969e177cf557322e3e047ea.html#a884e2844a969e177cf557322e3e047ea">mThreadPriority</a></td></tr>
<tr class="memdesc:a884e2844a969e177cf557322e3e047ea"><td class="mdescLeft">&#160;</td><td class="mdescRight">Number between -1.0 and 1.0 indicating the relative scheduling priority of the worker threads.  <a href="#a884e2844a969e177cf557322e3e047ea">More...</a><br/></td></tr>
<tr class="separator:a884e2844a969e177cf557322e3e047ea"><td class="memSeparator" colspan="2">&#160;</td></tr>
</table>
<a name="details" id="details"></a><h2 class="groupheader">Detailed Description</h2>
<div class="textblock"><p><a class="el" href="structTheron_1_1Framework_1_1Parameters.html" title="Parameters structure that can be passed to the Framework constructor. ">Parameters</a> structure that can be passed to the <a class="el" href="classTheron_1_1Framework.html" title="Manager class that hosts, manages, and executes actors. ">Framework</a> constructor. </p>
<p>When an instance of this structure is passed to the constructor of the <a class="el" href="classTheron_1_1Framework.html" title="Manager class that hosts, manages, and executes actors. ">Framework</a> class, its members can be used to configure the constructed framework.</p>
<p>The members are mainly concerned with configuring the pool of worker threads that is created within the framework, and which is used to execute the actors that are subsequently hosted within it. They allow the user to control the number of threads in the pool, their processor affinities, and their yielding behavior.</p>
<p>By choosing appropriate values it's possible to configure specialized frameworks tailored to particular uses. For example, users writing real-time systems might choose to create a separate framework for hosting actors whose execution is time-critical. Such a framework might be configured with the same number of threads as the number of hosted actors, ensuring that a free thread is always available to process actors with queued messages. Also, one might choose to dedicate a number of processor cores entirely to the execution of those threads, using processor affinity masks to limit execution of the worker threads of the framework to only the selected cores (leaving the remaining cores to other frameworks). Finally, since the cores dedicated to time-critical processing are never used for any other processing, one might choose to set the yield strategy of the worker threads to <a class="el" href="namespaceTheron_a03ee5f87e8369a84dc8f6f922677429c.html#a03ee5f87e8369a84dc8f6f922677429ca542d5ce1884d1dcbd2c45c17bd92bc3b">YIELD_STRATEGY_SPIN</a>, effectively busy-waiting for the arrival of new messages.</p>
<p>As well as setting processor affinities, the members of the <a class="el" href="structTheron_1_1Framework_1_1Parameters.html" title="Parameters structure that can be passed to the Framework constructor. ">Parameters</a> structure allow the node affinities of the worker threads to be controlled. This allows users to restrict the execution of a framework's worker threads to a particular <em>node</em> within a NUMA (Non-Uniform Memory Architecture) system.</p>
<p>A NUMA system is one in which the different logical cores within the physical CPU(s) have different views of memory, typically by virtue of being serviced by different physical memory controllers. In such systems, memory may be partitioned into areas that are each directly accessed by a single memory controller, with the cores fed by that controller enjoying faster access to that area of memory. Access to other parts of memory is indirectly served by other controllers, so is slower. Within the context of a NUMA system, a 'node' is a group of logical cores that share the same view of memory (typically by virtue of being serviced by the same memory controller).</p>
<p>Windows and Linux both provide APIs by which the node topology of a system can be discovered. These APIs allow the processor affinities of threads to be set on a per-node basis, limiting threads to execute only on the processors of a particular nodes (or set of nodes). Finally, they provide methods for allocating memory within the area of memory to which a particular node has first class access.</p>
<p>The scalability of a multi-threaded application can be improved by restricting threads that access the same memory to execute only on a limited subset of the available cores. Doing so can improve cache coherency due to the same memory being repeatedly accessed via the caches of those cores.</p>
<p>As threads read and write memory, cached copies of the memory accumulate in the caches local to the cores on which the threads are executed. When a thread writes to memory, any cached copies held in the caches of other cores are invalidated and must be re-fetched from memory. If other threads also write to the same piece of memory (known as <em>shared</em> <em>writes</em>), then the repeated cache invalidations and refreshes can cause significant overheads. These overheads can be especially severe, and can limit scalability, if the threads in question are allowed to execute on different NUMA nodes.</p>
<p>In <a class="el" href="namespaceTheron.html" title="Main namespace containing all public API components. ">Theron</a>, Frameworks serve as the mechanism by which worker threads are grouped. Accordingly, <a class="el" href="namespaceTheron.html" title="Main namespace containing all public API components. ">Theron</a> allows the node and processor affinities of worker threads to be set on a per-framework basis. The expectation is that the actors within a single framework will mainly message each other, with messages being sent between frameworks far less frequently.</p>
<dl class="section note"><dt>Note</dt><dd>Support for node and processor affinity masks is currently somewhat limited. Supported is implemented with Windows NUMA API in windows builds, and with libnuma under linux. In GCC builds, NUMA support requires libnuma-dev and must be explicitly enabled via <a class="el" href="Defines_8h_a6721c493481921173d9a7deb2d0d6a29.html#a6721c493481921173d9a7deb2d0d6a29">THERON_NUMA</a> (or numa=on in the makefile). The <a class="el" href="structTheron_1_1Framework_1_1Parameters_a22b5df6a6870c48ee49ee8d504a70995.html#a22b5df6a6870c48ee49ee8d504a70995">mNodeMask</a> member is supported with both version 1 and version 2 of the libnuma API, but the <a class="el" href="structTheron_1_1Framework_1_1Parameters_a42e97de63f2f50b40ac6071b524e972e.html#a42e97de63f2f50b40ac6071b524e972e">mProcessorMask</a> member is supported only with version 2. Under Windows both members are supported. </dd></dl>
</div></div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated by &#160;<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.8.5
</small></address>
</body>
</html>
